/*
 * Copyright 2012-2021 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.boot.web.embedded.tomcat;

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.stream.Collectors;

import javax.naming.NamingException;

import org.apache.catalina.Container;
import org.apache.catalina.Context;
import org.apache.catalina.Engine;
import org.apache.catalina.Lifecycle;
import org.apache.catalina.LifecycleException;
import org.apache.catalina.LifecycleState;
import org.apache.catalina.Service;
import org.apache.catalina.connector.Connector;
import org.apache.catalina.startup.Tomcat;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.naming.ContextBindings;

import org.springframework.boot.web.server.GracefulShutdownCallback;
import org.springframework.boot.web.server.GracefulShutdownResult;
import org.springframework.boot.web.server.PortInUseException;
import org.springframework.boot.web.server.Shutdown;
import org.springframework.boot.web.server.WebServer;
import org.springframework.boot.web.server.WebServerException;
import org.springframework.util.Assert;

/**
 * {@link WebServer} that can be used to control a Tomcat web server. Usually this class
 * should be created using the {@link TomcatReactiveWebServerFactory} or
 * {@link TomcatServletWebServerFactory}, but not directly.
 *
 * @author Brian Clozel
 * @author Kristine Jetzke
 * @since 2.0.0
 */
public class TomcatWebServer implements WebServer {

	private static final Log logger = LogFactory.getLog(TomcatWebServer.class);
    //AtomicInteger作为原子计数器
	private static final AtomicInteger containerCounter = new AtomicInteger(-1);

	private final Object monitor = new Object();

	private final Map<Service, Connector[]> serviceConnectors = new HashMap<>();

	private final Tomcat tomcat;

	private final boolean autoStart;

	private final GracefulShutdown gracefulShutdown;

	private volatile boolean started;

	/**
	 * Create a new {@link TomcatWebServer} instance.
	 * @param tomcat the underlying Tomcat server
	 */
	public TomcatWebServer(Tomcat tomcat) {
		this(tomcat, true);
	}

	/**
	 * Create a new {@link TomcatWebServer} instance.
	 * @param tomcat the underlying Tomcat server
	 * @param autoStart if the server should be started
	 */
	public TomcatWebServer(Tomcat tomcat, boolean autoStart) {
		this(tomcat, autoStart, Shutdown.IMMEDIATE);
	}

	/**
	 * Create a new {@link TomcatWebServer} instance.
	 * @param tomcat the underlying Tomcat server
	 * @param autoStart if the server should be started
	 * @param shutdown type of shutdown supported by the server
	 * @since 2.3.0
	 */
	public TomcatWebServer(Tomcat tomcat, boolean autoStart, Shutdown shutdown) {
		Assert.notNull(tomcat, "Tomcat Server must not be null");
		this.tomcat = tomcat;
		//设置是否要自动启动标志(true)
		this.autoStart = autoStart;
		//关闭方式是否为优雅式，默认为立即关闭式 ，此值默认为null
		this.gracefulShutdown = (shutdown == Shutdown.GRACEFUL) ? new GracefulShutdown(tomcat) : null;
		// 初始化当前Tomcat，主要是调用tomcat.start()，该初始化过程会初始化和启动tomcat的server,service,engine,会初始化相应的connector,
		// 但是并不会启动该connector, 而是将其删除，通过实现lifecycle的方式，在之后整个容器刷新完成后调用start()方法来启动connector
		initialize();
	}
    // 重命名tomcat弓|擎名称、对Context添加生命周期监听事件、启动服务触发初始化监听、检查TomcatStarter执行过程中是否存在异常在及Container状态是否正确、
	// 绑定命名到类加载器、启动非守护等待线程等
	private void initialize() throws WebServerException {
		logger.info("Tomcat initialized with port(s): " + getPortsDescription(false));
		synchronized (this.monitor) {
			try {
				// 往引擎名字中增加instance Id信息，如果 instance id为0，则不修改引擎名字
				addInstanceIdToEngineName();
                //获取context对象信息
				Context context = findContext();
				// 为context添加生命周期的监昕事件 注意：每一个组件都会有一个Lifecycle与之相对应  只有组件(connector,host,context等)和状态都符合才会执行
				context.addLifecycleListener((event) -> {
					// 这里的"删除"实际上是提供了一个事件响应函数，该事件响应函数会在context的生命周期事件START_EVENT发生时真正删除Service上的Connector，
					// 但是需要注意的是这里的事件响应和applicationListener事件监听是两码事  此处是每次发生状态变化时不会进行事件发布而是直接遍历集合，
					// 状态条件符合的LifecycleListener就会执行相应的方法
					if (context.equals(event.getSource()) && Lifecycle.START_EVENT.equals(event.getType())) {
						// Remove service connectors so that protocol binding doesn't
						// happen when the service is started.
						// 这里删除Connector的目的是在下面tomcat.start()启动过程中避免启动相应的Connector,而Connector启动通常意味着可以接收请求了，
						// 而此时Service尚未启动结束,所以要避免在Service启动过程中启动Connector，而是将其延后启动。
						removeServiceConnectors();
					}
				});

				// Start the server to trigger initialization listeners
				//启动服务，触发初始化监听，本方法并没有完全启动tomcat
				//利用LifecycleBase对这一套容器（engine，host，context及wrapper）进行启动并发布configure_start、before_init、after_start的lifecycleEvent等事件给相应的监听器

				// 1.触发启动Tomcat容器中除了Connector之外的其他部分，Connector此处没被启动意味着该启动过程完成后，服务器还是不能接受来自网络的请求,因为Connector
				// 才是真正负责接受网络请求的入口。
				// 2. 这里Tomcat启动的主要是StandardServer[1实例,Tomcat Lifecycle] =>StandardService[1实例,Tomcat Lifecycle] =>
				// StandardEngine[1实例,Tomcat Container] =异步startStopExecutor =>StandardHost[1实例,Tomcat Container] =异步startStopExecutor =>
				// TomcatEmbeddedContext[1实例,Springboot实现的Tomcat Container] =>StandardWrapper[1实例,Tomcat Container]。
				// 这里StandardWrapper对应的Servlet是Spring MVC的DispatchServlet。上面Tomcat Container父容器启动子容器都是通过线程池异步方式启动的。

				// 该方法中的server.start():启动  tomcat StandardServer。这里会对相应的server,service,engine,分别进行初始化和启动，也就是调用他们的init()
				// 方法和start()方法。而 connector只执行了初始化init(),然后被从service中删掉。该被删除的connector随后会被添加回来，
				// 然后再WebServerStartStopLifecycle中调用其启动start()方法。

				// 启动过程中Context启动时，上面提到的方法ServletWebServerApplicationContext#selfInitialize()会被调用
				// 然后在调用removeServiceConnectors()方法
				this.tomcat.start();

				// We can re-throw failure exception directly in the main thread
				//可以直接在主线程中重新抛出失败异常，TomcatStarter执行存在异常或状态错误均会抛出异常
				rethrowDeferredStartupExceptions();

				try {
					//绑定一个命名的context.到类加载器(https://blog.csdn.net/qq_43842093/article/details/125363775)
					ContextBindings.bindClassLoader(context, context.getNamingToken(), getClass().getClassLoader());
				}
				catch (NamingException ex) {
					// Naming is not enabled. Continue
					// 未启用命名，继续
				}

				// Unlike Jetty, all Tomcat threads are daemon threads. We create a
				// blocking non-daemon to stop immediate shutdown
				// tomcat 自身所有的线程都是daemon线程。这里spring创建了一个非daemon线程用来阻塞整个应用，避免刚启动就马上结束的情况。
				// 该线程每10秒检查一次tomcat是否接收到结束信号，如果接收到，则结束执行
				startDaemonAwaitThread();
			}
			catch (Exception ex) {
				// 异常停止和销毁tomcat
				stopSilently();
				destroySilently();
				throw new WebServerException("Unable to start embedded Tomcat", ex);
			}
		}
	}

	private Context findContext() {
		//这里直接获取Host的child作为context，一个host下可以含有多个context，但是这里使用的是内嵌形式，host下仅有一个context
		for (Container child : this.tomcat.getHost().findChildren()) {
			if (child instanceof Context) {
				return (Context) child;
			}
		}
		throw new IllegalStateException("The host does not contain a Context");
	}

	private void addInstanceIdToEngineName() {
		//以原子方式将当前值递增1并在递增后返回新值。它相当于i++操作
		int instanceId = containerCounter.incrementAndGet();
		if (instanceId > 0) {
			Engine engine = this.tomcat.getEngine();
			engine.setName(engine.getName() + "-" + instanceId);
		}
	}
	// Tomcat Connector是用来接收来自网络的请求的关键组件。这一部分组件启动之后，整个容器tomcatEmbeddedServletContainer
	// 才能接受和处理来自网络的请求从而为用户提供服务，所以所有这些的启动都结束，才能算是整个容器的启动完成，此时started属性才能设置为true
	private void removeServiceConnectors() {
		for (Service service : this.tomcat.getServer().findServices()) {
			Connector[] connectors = service.findConnectors().clone();
			// 将要移除的connector放到缓存中暂存
			this.serviceConnectors.put(service, connectors);
			for (Connector connector : connectors) {
				// Service启动过程中会获取其connector集合，如果不为空那么执行其start方法进行启动，而此处将connector移除后，
				// 那么service启动过程中获取的connector集合为null，也就无法在执行其start方法
				service.removeConnector(connector);
			}
		}
	}

	private void rethrowDeferredStartupExceptions() throws Exception {
		//获取host的子容器，即context
		Container[] children = this.tomcat.getHost().findChildren();
		for (Container container : children) {
			if (container instanceof TomcatEmbeddedContext) {
				//得到封装在context中的TomcatStarter
				TomcatStarter tomcatStarter = ((TomcatEmbeddedContext) container).getStarter();
				if (tomcatStarter != null) {
					//TomcatStarter在执行中如果有异常会被封装到startUpException集合中，如果该集合不为空，那么直接抛出其收集到的异常信息
					Exception exception = tomcatStarter.getStartUpException();
					if (exception != null) {
						throw exception;
					}
				}
			}
			//到达这个阶段，整个tomcat的生命周期context组件一定是after_start阶段，否则异常抛出
			if (!LifecycleState.STARTED.equals(container.getState())) {
				throw new IllegalStateException(container + " failed to start");
			}
		}
	}

	private void startDaemonAwaitThread() {
		Thread awaitThread = new Thread("container-" + (containerCounter.get())) {

			@Override
			public void run() {
				// 等待收到正确的关机命令，然后返回,否则就处于阻塞状态
				TomcatWebServer.this.tomcat.getServer().await();
			}

		};
		awaitThread.setContextClassLoader(getClass().getClassLoader());
		awaitThread.setDaemon(false);
		awaitThread.start();
	}

	@Override
	public void start() throws WebServerException {
		synchronized (this.monitor) {
			//this.started为false,只有当connector正常启动之后才会将该值设置为true
			if (this.started) {
				return;
			}
			try {
				// 将内置容器创建和初始化阶段删除的Connector再添加到容器，将Connector添加回容器(实际上是添加到容器的Service)，
				// 因为相应的Service已经处于启动状态，所以Connector在添加回来之后马上会被启动
				addPreviouslyRemovedConnectors();
				// 获得tomcat的Connector，如果不为空并且设置为自动启动，则启动之。缺省配置下，这里autoStart为true
				// 连接器Connector主要是接收用户的请求，然后封装请求传递给容器处理，tomcat中默认的连接器是Coyote。连接器表示Tomcat将会在哪个端口使用哪种协议提供服务。
				// 在配置文件中，我们经常会见到这样的配置 :
				// <Connector port="8080" protocol="HTTP/1.1"  connectionTimeout="20000"
				//                redirectPort="8443" URIEncoding="utf-8"/>
				// <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
				Connector connector = this.tomcat.getConnector();
				if (connector != null && this.autoStart) {
					/* wrapper(servlet)延迟加载启动,对符合条件的servlet执行init初始化过程*/
					performDeferredLoadOnStartup();
				}
				// 检查确保Connector已经启动，如果没启动，抛出异常
				checkThatConnectorsHaveStarted();
				this.started = true;
				logger.info("Tomcat started on port(s): " + getPortsDescription(true) + " with context path '"
						+ getContextPath() + "'");
			}
			catch (ConnectorStartFailedException ex) {
				// 异常停止tomcat
				stopSilently();
				throw ex;
			}
			catch (Exception ex) {
				PortInUseException.throwIfPortBindingException(ex, () -> this.tomcat.getConnector().getPort());
				throw new WebServerException("Unable to start embedded Tomcat server", ex);
			}
			finally {
				Context context = findContext();
				// context解绑ClassLoader
				ContextBindings.unbindClassLoader(context, context.getNamingToken(), getClass().getClassLoader());
			}
		}
	}

	private void checkThatConnectorsHaveStarted() {
		//检查connector的状态
		checkConnectorHasStarted(this.tomcat.getConnector());
		for (Connector connector : this.tomcat.getService().findConnectors()) {
			checkConnectorHasStarted(connector);
		}
	}

	private void checkConnectorHasStarted(Connector connector) {
		//判断connector的状态是否为failed,如果是则异常抛出
		if (LifecycleState.FAILED.equals(connector.getState())) {
			throw new ConnectorStartFailedException(connector.getPort());
		}
	}

	private void stopSilently() {
		try {
			stopTomcat();
		}
		catch (LifecycleException ex) {
			// Ignore
		}
	}

	private void destroySilently() {
		try {
			this.tomcat.destroy();
		}
		catch (LifecycleException ex) {
			// Ignore
		}
	}

	private void stopTomcat() throws LifecycleException {
		if (Thread.currentThread().getContextClassLoader() instanceof TomcatEmbeddedWebappClassLoader) {
			Thread.currentThread().setContextClassLoader(getClass().getClassLoader());
		}
		this.tomcat.stop();
	}

	private void addPreviouslyRemovedConnectors() {
		Service[] services = this.tomcat.getServer().findServices();
		for (Service service : services) {
			// 获取从上面移除connector添加到缓存中的connector
			Connector[] connectors = this.serviceConnectors.get(service);
			if (connectors != null) {
				for (Connector connector : connectors) {
					// 此时service已经处于启动状态，因此重新添加进来的connector。会根据available的值来决定是否立即启动
					// 当tomcat正常启动之后，会将available设置为true，表示当前tomcat为可用状态
					service.addConnector(connector);
					//设置的端口大于0，那么该值在webserver初始化的时候即为true
					if (!this.autoStart) {
						// 如果不是自动启动，则暂停connector
						stopProtocolHandler(connector);
					}
				}
				// 添加完成后移除
				this.serviceConnectors.remove(service);
			}
		}
	}

	private void stopProtocolHandler(Connector connector) {
		try {
			connector.getProtocolHandler().stop();
		}
		catch (Exception ex) {
			logger.error("Cannot pause connector: ", ex);
		}
	}

	private void performDeferredLoadOnStartup() {
		try {
			for (Container child : this.tomcat.getHost().findChildren()) {
				if (child instanceof TomcatEmbeddedContext) {
					/* 延迟加载启动 */
					((TomcatEmbeddedContext) child).deferredLoadOnStartup();
				}
			}
		}
		catch (Exception ex) {
			if (ex instanceof WebServerException) {
				throw (WebServerException) ex;
			}
			throw new WebServerException("Unable to start embedded Tomcat connectors", ex);
		}
	}

	Map<Service, Connector[]> getServiceConnectors() {
		return this.serviceConnectors;
	}

	@Override
	public void stop() throws WebServerException {
		synchronized (this.monitor) {
			boolean wasStarted = this.started;
			try {
				this.started = false;
				try {
					if (this.gracefulShutdown != null) {
						this.gracefulShutdown.abort();
					}
					// 停止tomcat
					stopTomcat();
					// 销毁服务，调用后对象不能再次使用
					this.tomcat.destroy();
				}
				catch (LifecycleException ex) {
					// swallow and continue
				}
			}
			catch (Exception ex) {
				throw new WebServerException("Unable to stop embedded Tomcat", ex);
			}
			finally {
				if (wasStarted) {
					containerCounter.decrementAndGet();
				}
			}
		}
	}

	private String getPortsDescription(boolean localPort) {
		StringBuilder ports = new StringBuilder();
		for (Connector connector : this.tomcat.getService().findConnectors()) {
			if (ports.length() != 0) {
				ports.append(' ');
			}
			int port = localPort ? connector.getLocalPort() : connector.getPort();
			ports.append(port).append(" (").append(connector.getScheme()).append(')');
		}
		return ports.toString();
	}

	@Override
	public int getPort() {
		Connector connector = this.tomcat.getConnector();
		if (connector != null) {
			return connector.getLocalPort();
		}
		return -1;
	}

	private String getContextPath() {
		return Arrays.stream(this.tomcat.getHost().findChildren()).filter(TomcatEmbeddedContext.class::isInstance)
				.map(TomcatEmbeddedContext.class::cast).map(TomcatEmbeddedContext::getPath)
				.collect(Collectors.joining(" "));
	}

	/**
	 * Returns access to the underlying Tomcat server.
	 * @return the Tomcat server
	 */
	public Tomcat getTomcat() {
		return this.tomcat;
	}

	@Override
	public void shutDownGracefully(GracefulShutdownCallback callback) {
		if (this.gracefulShutdown == null) {
			callback.shutdownComplete(GracefulShutdownResult.IMMEDIATE);
			return;
		}
		this.gracefulShutdown.shutDownGracefully(callback);
	}

}
